<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Extended timer for OpenResty</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>lua-resty-timer</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Status">Status </a></li>
<li><a href="#Synopsis">Synopsis </a></li>
<li><a href="#Description">Description </a></li>
<li><a href="#History">History </a></li>
<li><a href="#Copyright_and_License">Copyright and License </a></li>
</ul>


<h2>Topics</h2>
<ul class="">
  <li><strong>README</strong></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
  <li><a href="../index.html">resty.timer</a></li>
</ul>

</div>

<div id="content">


<h1>lua-resty-timer</h1>

<p><a href="https://travis-ci.org/Kong/lua-resty-timer/branches"><img src="https://travis-ci.org/Kong/lua-resty-timer.svg?branch=master" alt="Build Status"/></a></p>

<p>Extended timers for OpenResty. Provided recurring, cancellable, node-wide timers,
beyond what the basic OpenResty timers do.</p>

<p><a name="Status"></a></p>
<h2>Status</h2>

<p>This library is production ready.</p>

<p><a name="Synopsis"></a></p>
<h2>Synopsis</h2>


<pre>
http {
    lua_shared_dict timer_shm <span class="number">1</span>m;
    init_worker_by_lua_block {
        <span class="keyword">local</span> timer = <span class="global">require</span>(<span class="string">"resty.timer"</span>)

        <span class="keyword">local</span> options = {
            interval = <span class="number">0.1</span>,           <span class="comment">-- expiry interval in seconds
</span>            recurring = <span class="keyword">true</span>,         <span class="comment">-- recurring or single timer
</span>            immediate = <span class="keyword">true</span>,         <span class="comment">-- initial interval will be 0
</span>            detached = <span class="keyword">false</span>,         <span class="comment">-- run detached, or be garbagecollectible
</span>            jitter = <span class="number">0.1</span>,             <span class="comment">-- add a random interval
</span>            expire = object.handler,  <span class="comment">-- callback on timer expiry
</span>            cancel = <span class="keyword">function</span>(reason, self, param1)
                <span class="comment">-- will be called when the timer gets cancelled
</span>            <span class="keyword">end</span>,
            shm_name = <span class="string">"timer_shm"</span>,   <span class="comment">-- shm to use for node-wide timers
</span>            key_name = <span class="string">"my_key"</span>,      <span class="comment">-- key-name to use for node-wide timers
</span>            sub_interval = <span class="number">0.1</span>,       <span class="comment">-- max cross worker extra delay
</span>        }

        <span class="keyword">local</span> object
        object = {                            <span class="comment">-- create some object with a timer
</span>            count = <span class="number">0</span>,
            handler = <span class="keyword">function</span>(self, param1)  <span class="comment">-- the timer callback as a method
</span>                <span class="comment">-- do something here
</span>                <span class="global">print</span>(param1)                 <span class="comment">--&gt; "Param 1"
</span>            <span class="keyword">end</span>,

            <span class="comment">-- create and add to object, but also pass it as 'self' to the handler
</span>            timer = timer(options, object, <span class="string">"Param 1"</span>),
        }

        <span class="comment">-- anchor the object and timer
</span>        _M.global_object = object     <span class="comment">-- will be collected if not anchored
</span>
        <span class="comment">-- cancel the timer
</span>        object.timer:cancel()
    }
}
</pre>


<p><a name="Description"></a></p>
<h2>Description</h2>

<p>The OpenResty timer is fairly limited, this timer adds a number of common
options as parameters without having to recode (and retest) them in each
project.</p>

<ul>
    <li><p>recurring timers (supported by OR as well through <code>ngx.timer.every</code>)</p></li>
    <li><p>immediate first run for recurring timers</p></li>
    <li><p>cancellable timers</p></li>
    <li><p>cancel callback, called when the timer is cancelled</p></li>
    <li><p>garbage collectible timers, enabling timers to (optionally) be attached to
    objects and automatically stop when garbage collected.</p></li>
    <li><p>node-wide timers: the same timer started in each worker will still only
    run once across the system. If the worker running it is removed the
    timer will automatically be executed on another worker.</p></li>
</ul>

<p>See the <a href="https://kong.github.io/lua-resty-timer/topics/README.md.html">online LDoc documentation</a>
for the complete API.</p>

<p><a name="History"></a></p>
<h2>History</h2>

<p>Versioning is strictly based on <a href="https://semver.org/">Semantic Versioning</a></p>

<h3>Releasing new versions:</h3>

<ul>
    <li>update changelog below (PR's should be merged including a changelog entry)</li>
    <li>based on changelog determine new SemVer version</li>
    <li>create a new rockspec</li>
    <li>render the docs using <code>ldoc</code> (don't do this within PR's)</li>
    <li>commit as "release x.x.x" (do not include rockspec revision)</li>
    <li>tag the commit with "x.x.x" (do not include rockspec revision)</li>
    <li>push commit and tag</li>
    <li>upload rock to luarocks: <code>luarocks upload rockspecs/[name] --api-key=abc</code></li>
</ul>

<h3>1.1.0 (6-Nov-2020)</h3>

<ul>
    <li>Feat: add a <code>jitter</code> option. This adds a random interval to distribute the
    timers (in case of scheduling many timers at once).</li>
</ul>

<h3>1.0.0 (21-Sep-2020)</h3>

<ul>
    <li>Change [BREAKING]: the recurring timers are now implemented as a sleeping
    thread which is more efficient. Side effect is that the timer only gets
    rescheduled AFTER executing the handler. So if the handler is long running,
    then individual runs will be further apart.</li>
</ul>

<h3>0.3 (28-May-2018)</h3>

<ul>
    <li>Feat: added cancellation callback invocation on timer being GC'ed. This
    changes the first argument of the <a href="../index.html#cancel">cancel</a> callback, and hence is
    breaking.</li>
</ul>

<h3>0.2 (12-Feb-2018) Bug fix</h3>

<ul>
    <li>Fix: bugfix in <a href="https://www.lua.org/manual/5.1/manual.html#pdf-unpack">unpack</a> function not honoring table length parameter</li>
    <li>Docs: small fixes and typo's</li>
</ul>

<h3>0.1 (22-Nov-2017) Initial release</h3>

<ul>
    <li>Added <code>sub_interval</code> option to reduce delays</li>
    <li>Initial upload</li>
</ul>

<p><a name="Copyright_and_License"></a></p>
<h2>Copyright and License</h2>

<pre><code> Copyright 2017 - 2018 Kong Inc.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
</code></pre>




</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-11-07 00:01:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
